Guidelines for Writing Code for 64-Bit Silicon Graphics Platforms

The following guidelines help you to produce portable code. Use these guidelines when you are developing new code or as you identify portability problems in existing code.

1. In a header file that you include in each of the program's source files, define (typedef) a type for each of the following functions:

   • For each specific integer data size required, that is, where exactly the same number of bits is required on each target, define a signed and unsigned type. For example:

     typedef signed char int8_t

     typedef unsigned char uint8_t

     ...

     typedef unsigned long long uint64_t

   • If you require a large scaling integer type, that is, one that is as large as possible while remaining efficiently supported by the target, define another pair of types. For example:

     typedef signed long intscaled_t

     typedef unsigned long uintscaled_t

   • If you require integer types of at least a particular size, but chosen for maximally efficient implementation on the target, define another set of types, similar to the first but defined as larger standard types where appropriate for efficiency. The typedefs referred to above exist in the file inttypes.h (see "Using Typedefs").

     After you construct the above header file, use the new typedef types instead of the standard C type names. You may need a distinct copy of this header file (or conditional code) for each target platform supported.

     If you provide libraries or interfaces to be used by others, be careful to use these types (or similar application-specific types) chosen to match the specific requirements of the interface. Also, carefully choose the actual names used to avoid namespace conflicts with other libraries. Thus, your clients should be able to use a single set of header files on all targets. However, you will always need to provide distinct libraries (binaries) for the 32-bit compatibility mode and the 64-bit native mode on 64-bit Silicon Graphics platforms, although the sources can be identical.

2. Be sure to specify constants with an appropriate type specifier so that they will have the size required by the context with the values expected. Bit masks can be particularly troublesome in this regard: avoid using constants for negative values. For example, 0xffffffff may be equivalent to a -1 on 32-bit systems, but may be interpreted as 4,294,967,295 (signed or unsigned, depending on the mode and context) on most 64-bit systems. The inttypes.h header file provides cpp macros to facilitate this conversion. Defining constants that are sensitive to type sizes in a central header file may help in modifying them when a new port is done.

3. Where printf/scanf are used for objects whose types are typedefed differently among the targets you must support, you may need to define constant format strings for each of the types defined in step 1. For example:

   #define _fmt32 "%d"

   #define _fmt32u "%u"

   #define _fmt64 "%lld"

   #define _fmt64u "%llu"

   The inttypes.h header file also defines printf/scanf format extensions to standardize these practices. They are implemented by the first release of the 64-bit compilers and related tools.

This chapter provides guidelines for porting code.